Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Trilead SSH-2 for Java
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trilead.ssh2
Class SFTPv3Client

    java.lang.Object
      com.trilead.ssh2.SFTPv3Client

    public class SFTPv3Client

extends java.lang.Object

A `SFTPv3Client` represents a SFTP (protocol version 3) client connection tunnelled over a SSH-2 connection. This is a very simple (synchronous) implementation.

Basically, most methods in this class map directly to one of the packet types described in draft-ietf-secsh-filexfer-02.txt.

Note: this is experimental code.

Error handling: the methods of this class throw IOExceptions. However, unless there is catastrophic failure, exceptions of the type `SFTPv3Client` will be thrown (a subclass of IOException). Therefore, you can implement more verbose behavior by checking if a thrown exception if of this type. If yes, then you can cast the exception and access detailed information about the failure.

Notes about file names, directory names and paths, copy-pasted from the specs:

- SFTP v3 represents file names as strings. File names are assumed to use the slash ('/') character as a directory separator.
- File names starting with a slash are "absolute", and are relative to the root of the file system. Names starting with any other character are relative to the user's default directory (home directory).
- Servers SHOULD interpret a path name component ".." as referring to the parent directory, and "." as referring to the current directory. If the server implementation limits access to certain parts of the file system, it must be extra careful in parsing file names when enforcing such restrictions. There have been numerous reported security bugs where a ".." in a path name has allowed access outside the intended area.
- An empty path name is valid, and it refers to the user's default directory (usually the user's home directory).

If you are still not tired then please go on and read the comment for `setCharset(String)`.

Version:
  $Id: SFTPv3Client.java,v 1.3 2008/04/01 12:38:09 cplattne Exp $
Author:
  Christian Plattner, plattner@trilead.com

Constructor Summary
`SFTPv3Client(Connection conn)` Create a SFTP v3 client.
`SFTPv3Client(Connection conn, java.io.PrintStream debug)` Deprecated. this constructor (debug version) will disappear in the future, use `SFTPv3Client(Connection)` instead.

Method Summary
`java.lang.String` | `canonicalPath(java.lang.String path)` Have the server canonicalize any given path name to an absolute path.
`void` | `close()` Close this SFTP session.
`void` | `closeFile(SFTPv3FileHandle handle)` Close a file.
`SFTPv3FileHandle` | `createFile(java.lang.String fileName)` Create a file and open it for reading and writing.
`SFTPv3FileHandle` | `createFile(java.lang.String fileName, SFTPv3FileAttributes attr)` Create a file and open it for reading and writing.
`SFTPv3FileHandle` | `createFileTruncate(java.lang.String fileName)` Create a file (truncate it if it already exists) and open it for reading and writing.
`SFTPv3FileHandle` | `createFileTruncate(java.lang.String fileName, SFTPv3FileAttributes attr)` reate a file (truncate it if it already exists) and open it for reading and writing.
`void` | `createSymlink(java.lang.String src, java.lang.String target)` Create a symbolic link on the server.
`void` | `fsetstat(SFTPv3FileHandle handle, SFTPv3FileAttributes attr)` Modify the attributes of a file.
`SFTPv3FileAttributes` | `fstat(SFTPv3FileHandle handle)` Retrieve the file attributes of an open file.
`java.lang.String` | `getCharset()` The currently used charset for filename encoding/decoding.
`int` | `getProtocolVersion()` Returns the negotiated SFTP protocol version between the client and the server.
`java.util.Vector` | `ls(java.lang.String dirName)` List the contents of a directory.
`SFTPv3FileAttributes` | `lstat(java.lang.String path)` Retrieve the file attributes of a file.
`void` | `mkdir(java.lang.String dirName, int posixPermissions)` Create a new directory.
`void` | `mv(java.lang.String oldPath, java.lang.String newPath)` Move a file or directory.
`SFTPv3FileHandle` | `openFileRO(java.lang.String fileName)` Open a file for reading.
`SFTPv3FileHandle` | `openFileRW(java.lang.String fileName)` Open a file for reading and writing.
`int` | `read(SFTPv3FileHandle handle, long fileOffset, byte[] dst, int dstoff, int len)` Read bytes from a file.
`java.lang.String` | `readLink(java.lang.String path)` Read the target of a symbolic link.
`void` | `rm(java.lang.String fileName)` Remove a file.
`void` | `rmdir(java.lang.String dirName)` Remove an empty directory.
`void` | `setCharset(java.lang.String charset)` Set the charset used to convert between Java Unicode Strings and byte encodings used by the server for paths and file names.
`void` | `setstat(java.lang.String path, SFTPv3FileAttributes attr)` Modify the attributes of a file.
`SFTPv3FileAttributes` | `stat(java.lang.String path)` Retrieve the file attributes of a file.
`void` | `write(SFTPv3FileHandle handle, long fileOffset, byte[] src, int srcoff, int len)` Write bytes to a file.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### SFTPv3Client

    public SFTPv3Client(Connection conn,
                        java.io.PrintStream debug)
                 throws java.io.IOException

  Deprecated. this constructor (debug version) will disappear in the future, use `SFTPv3Client(Connection)` instead.

  Create a SFTP v3 client.

  Parameters:
    `conn` - The underlying SSH-2 connection to be used.
    `debug` -
  Throws:
    `java.io.IOException`

### SFTPv3Client

    public SFTPv3Client(Connection conn)
                 throws java.io.IOException

  Create a SFTP v3 client.

  Parameters:
    `conn` - The underlying SSH-2 connection to be used.
  Throws:
    `java.io.IOException`

Method Detail

### setCharset

    public void setCharset(java.lang.String charset)
                    throws java.io.IOException

  Set the charset used to convert between Java Unicode Strings and byte encodings used by the server for paths and file names. Unfortunately, the SFTP v3 draft says NOTHING about such conversions (well, with the exception of error messages which have to be in UTF-8). Newer drafts specify to use UTF-8 for file names (if I remember correctly). However, a quick test using OpenSSH serving a EXT-3 filesystem has shown that UTF-8 seems to be a bad choice for SFTP v3 (tested with filenames containing german umlauts). "windows-1252" seems to work better for Europe. Luckily, "windows-1252" is the platform default in my case =).

  If you don't set anything, then the platform default will be used (this is the default behavior).

  Parameters:
    `charset` - the name of the charset to be used or `null` to use the platform's default encoding.
  Throws:
    `java.io.IOException`
  See Also:
    `getCharset()`

### getCharset

    public java.lang.String getCharset()

  The currently used charset for filename encoding/decoding.

  Returns:
    The name of the charset (`null` if the platform's default charset is being used)
  See Also:
    `setCharset(String)`

### fstat

    public SFTPv3FileAttributes fstat(SFTPv3FileHandle handle)
                               throws java.io.IOException

  Retrieve the file attributes of an open file.

  Parameters:
    `handle` - a SFTPv3FileHandle handle.
  Returns:
    a SFTPv3FileAttributes object.
  Throws:
    `java.io.IOException`

### stat

    public SFTPv3FileAttributes stat(java.lang.String path)
                              throws java.io.IOException

  Retrieve the file attributes of a file. This method follows symbolic links on the server.

  Parameters:
    `path` - See the `comment` for the class for more details.
  Returns:
    a SFTPv3FileAttributes object.
  Throws:
    `java.io.IOException`
  See Also:
    `lstat(String)`

### lstat

    public SFTPv3FileAttributes lstat(java.lang.String path)
                               throws java.io.IOException

  Retrieve the file attributes of a file. This method does NOT follow symbolic links on the server.

  Parameters:
    `path` - See the `comment` for the class for more details.
  Returns:
    a SFTPv3FileAttributes object.
  Throws:
    `java.io.IOException`
  See Also:
    `stat(String)`

### readLink

    public java.lang.String readLink(java.lang.String path)
                              throws java.io.IOException

  Read the target of a symbolic link.

  Parameters:
    `path` - See the `comment` for the class for more details.
  Returns:
    The target of the link.
  Throws:
    `java.io.IOException`

### setstat

    public void setstat(java.lang.String path,
                        SFTPv3FileAttributes attr)
                 throws java.io.IOException

  Modify the attributes of a file. Used for operations such as changing the ownership, permissions or access times, as well as for truncating a file.

  Parameters:
    `path` - See the `comment` for the class for more details.
    `attr` - A SFTPv3FileAttributes object. Specifies the modifications to be made to the attributes of the file. Empty fields will be ignored.
  Throws:
    `java.io.IOException`

### fsetstat

    public void fsetstat(SFTPv3FileHandle handle,
                         SFTPv3FileAttributes attr)
                  throws java.io.IOException

  Modify the attributes of a file. Used for operations such as changing the ownership, permissions or access times, as well as for truncating a file.

  Parameters:
    `handle` - a SFTPv3FileHandle handle
    `attr` - A SFTPv3FileAttributes object. Specifies the modifications to be made to the attributes of the file. Empty fields will be ignored.
  Throws:
    `java.io.IOException`

### createSymlink

    public void createSymlink(java.lang.String src,
                              java.lang.String target)
                       throws java.io.IOException

  Create a symbolic link on the server. Creates a link "src" that points to "target".

  Parameters:
    `src` - See the `comment` for the class for more details.
    `target` - See the `comment` for the class for more details.
  Throws:
    `java.io.IOException`

### canonicalPath

    public java.lang.String canonicalPath(java.lang.String path)
                                   throws java.io.IOException

  Have the server canonicalize any given path name to an absolute path. This is useful for converting path names containing ".." components or relative pathnames without a leading slash into absolute paths.

  Parameters:
    `path` - See the `comment` for the class for more details.
  Returns:
    An absolute path.
  Throws:
    `java.io.IOException`

### getProtocolVersion

    public int getProtocolVersion()

  Returns the negotiated SFTP protocol version between the client and the server.

  Returns:
    SFTP protocol version, i.e., "3".

### close

    public void close()

  Close this SFTP session. NEVER forget to call this method to free up resources - even if you got an exception from one of the other methods. Sometimes these other methods may throw an exception, saying that the underlying channel is closed (this can happen, e.g., if the other server sent a close message.) However, as long as you have not called the `close()` method, you are likely wasting resources.

### ls

    public java.util.Vector ls(java.lang.String dirName)
                        throws java.io.IOException

  List the contents of a directory.

  Parameters:
    `dirName` - See the `comment` for the class for more details.
  Returns:
    A Vector containing `SFTPv3DirectoryEntry` objects.
  Throws:
    `java.io.IOException`

### mkdir

    public void mkdir(java.lang.String dirName,
                      int posixPermissions)
               throws java.io.IOException

  Create a new directory.

  Parameters:
    `dirName` - See the `comment` for the class for more details.
    `posixPermissions` - the permissions for this directory, e.g., "0700" (remember that this is octal noation). The server will likely apply a umask.
  Throws:
    `java.io.IOException`

### rm

    public void rm(java.lang.String fileName)
            throws java.io.IOException

  Remove a file.

  Parameters:
    `fileName` - See the `comment` for the class for more details.
  Throws:
    `java.io.IOException`

### rmdir

    public void rmdir(java.lang.String dirName)
               throws java.io.IOException

  Remove an empty directory.

  Parameters:
    `dirName` - See the `comment` for the class for more details.
  Throws:
    `java.io.IOException`

### mv

    public void mv(java.lang.String oldPath,
                   java.lang.String newPath)
            throws java.io.IOException

  Move a file or directory.

  Parameters:
    `oldPath` - See the `comment` for the class for more details.
    `newPath` - See the `comment` for the class for more details.
  Throws:
    `java.io.IOException`

### openFileRO

    public SFTPv3FileHandle openFileRO(java.lang.String fileName)
                                throws java.io.IOException

  Open a file for reading.

  Parameters:
    `fileName` - See the `comment` for the class for more details.
  Returns:
    a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

### openFileRW

    public SFTPv3FileHandle openFileRW(java.lang.String fileName)
                                throws java.io.IOException

  Open a file for reading and writing.

  Parameters:
    `fileName` - See the `comment` for the class for more details.
  Returns:
    a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

### createFile

    public SFTPv3FileHandle createFile(java.lang.String fileName)
                                throws java.io.IOException

  Create a file and open it for reading and writing. Same as `createFile(fileName, null)`.

  Parameters:
    `fileName` - See the `comment` for the class for more details.
  Returns:
    a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

### createFile

    public SFTPv3FileHandle createFile(java.lang.String fileName,
                                       SFTPv3FileAttributes attr)
                                throws java.io.IOException

  Create a file and open it for reading and writing. You can specify the default attributes of the file (the server may or may not respect your wishes).

  Parameters:
    `fileName` - See the `comment` for the class for more details.
    `attr` - may be `null` to use server defaults. Probably only the `uid`, `gid` and `permissions` (remember the server may apply a umask) entries of the `SFTPv3FileHandle` structure make sense. You need only to set those fields where you want to override the server's defaults.
  Returns:
    a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

### createFileTruncate

    public SFTPv3FileHandle createFileTruncate(java.lang.String fileName)
                                        throws java.io.IOException

  Create a file (truncate it if it already exists) and open it for reading and writing. Same as `createFileTruncate(fileName, null)`.

  Parameters:
    `fileName` - See the `comment` for the class for more details.
  Returns:
    a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

### createFileTruncate

    public SFTPv3FileHandle createFileTruncate(java.lang.String fileName,
                                               SFTPv3FileAttributes attr)
                                        throws java.io.IOException

  reate a file (truncate it if it already exists) and open it for reading and writing. You can specify the default attributes of the file (the server may or may not respect your wishes).

  Parameters:
    `fileName` - See the `comment` for the class for more details.
    `attr` - may be `null` to use server defaults. Probably only the `uid`, `gid` and `permissions` (remember the server may apply a umask) entries of the `SFTPv3FileHandle` structure make sense. You need only to set those fields where you want to override the server's defaults.
  Returns:
    a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

### read

    public int read(SFTPv3FileHandle handle,
                    long fileOffset,
                    byte[] dst,
                    int dstoff,
                    int len)
             throws java.io.IOException

  Read bytes from a file. No more than 32768 bytes may be read at once. Be aware that the semantics of read() are different than for Java streams.

  - The server will read as many bytes as it can from the file (up to `len`), and return them.
  - If EOF is encountered before reading any data, `-1` is returned.
  - If an error occurs, an exception is thrown
  .
  - For normal disk files, it is guaranteed that the server will return the specified number of bytes, or up to end of file. For, e.g., device files this may return fewer bytes than requested.

  Parameters:
    `handle` - a SFTPv3FileHandle handle
    `fileOffset` - offset (in bytes) in the file
    `dst` - the destination byte array
    `dstoff` - offset in the destination byte array
    `len` - how many bytes to read, 0 < len <= 32768 bytes
  Returns:
    the number of bytes that could be read, may be less than requested if the end of the file is reached, -1 is returned in case of `EOF`
  Throws:
    `java.io.IOException`

### write

    public void write(SFTPv3FileHandle handle,
                      long fileOffset,
                      byte[] src,
                      int srcoff,
                      int len)
               throws java.io.IOException

  Write bytes to a file. If `len` > 32768, then the write operation will be split into multiple writes.

  Parameters:
    `handle` - a SFTPv3FileHandle handle.
    `fileOffset` - offset (in bytes) in the file.
    `src` - the source byte array.
    `srcoff` - offset in the source byte array.
    `len` - how many bytes to write.
  Throws:
    `java.io.IOException`

### closeFile

    public void closeFile(SFTPv3FileHandle handle)
                   throws java.io.IOException

  Close a file.

  Parameters:
    `handle` - a SFTPv3FileHandle handle
  Throws:
    `java.io.IOException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Trilead SSH-2 for Java
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD